QuickTime 4 Reference

Adding an 'atms' Resource to your Component

The 'atms' resource for your effect contains two sets of information. The first set contains the effect information that is used to construct the standard parameters dialog box. This includes items such as the name of your effect and optional copyright information.

The second set contains the parameter information, which is a description of each parameter that your effect takes. If your effect does not take parameters, there is no information in this set.

The structure of an 'atms' resource is as follows:



 
resource 'atms' (kEffectatmsRes) {

7,

{

    // The resource body goes here

};

};

The header for this resource contains two items: the resource ID, and the number of root level atoms the resource contains.

The first line contains the ID of the 'atms' resource. In this example, the identifier that is used (kEffectatmsRes ) is also used in the call to GetComponentResource in Listing 14 . This ensures that the right 'atms' resource is read by QuickTime.

The second line contains the number of root atoms in the resource. Each 'atms' resource contains a number of atoms. The number in the second line must contain a count of the number of first-level atoms in the resource.

Warning
It is critical that you update this number if you add or delete atoms from your 'atms' resource. If this number is larger than the number of atoms in your effect, your effect component can cause QuickTime to crash. If this number is smaller than the number of atoms actually in the resource, users will not be able to adjust the values of some parameters.

The body of the 'atms' resource consists of a number of atom declarations. Each declaration has a header that contains

the atom name
the atom ID
the number of children in the declaration

Each header is followed by the atom's data, which is one or more typed values, such as a string or a long , or a set of child atoms.

Listing 15 shows an example atom that contains a single typed value as its data. Note that the value is a type followed by the data itself. The number of children of the atom is declared as noChildren because the atom contains a typed value.

Listing 15 An example 'atms' atom declaration



 
kParameterTitleName, kParameterTitleID, noChildren,

{

    string { "Dimmer2 Effect Parameters" };

};

The Standard Information in an 'atms' Resource

The standard information stored in an 'atms' resource is made up of three required atoms and five optional atoms.

The three required atoms are

kParameterTitleName: a string used as the title of the standard parameters dialog box. An example of a kParameterTitleName atom declaration is shown in Listing 15 .
kParameterWhatName: an OSType containing the name of this effect component.
kParameterSourceCountName: a long integer containing the maximum number of sources that the effect can take.

The five optional atoms are

kParameterAlternateCodecName: an OSType containing the unique identifier of another effect component that should be used to replace this effect if this effect cannot be used.
kParameterInfoLongName: a string containing the long version of the name of the effect.
kParameterInfoCopyright: a string containing a copyright statement for the effect.
kParameterInfoDescription: a string containing a brief description of what the effect does.
kParameterInfoWindowTitle: a string containing the title of the window that displays the information contained in the optional atoms.

The Parameter Information in an 'atms' Resource

For each parameter of the effect, your 'atms' resource must contain a set of atoms in the 'atms' resource that describes that parameter. This description includes the name of the parameter, the type and range of values it can take, and hints on appropriate user interface element for setting this parameter.

A complete description of the information you need to provide for each parameter can be found in "The Parameter Description Format" .

For a basic parameter, there are five atoms that you should supply:

kParameterAtomTypeAndID: contains the type and ID of the parameter (an OSType and a long integer, respectively), the atom flags for the parameter, and a string containing the name of the parameter.
kParameterDataType: a long integer containing the type of the parameter, such as kParameterTypeDataFixed .
kParameterDataRange: a set of typed values describing the range of values the parameter can take. The number and type of values you supply depend on the value of the kParameterDataType atom.
kParameterDataBehavior: two long integer values containing the behavior type, such as kParameterItemControl for a slider, and any flags, such as kAtomNotInterpolated for a parameter that cannot be tweened.
kParameterDataDefaultItem: the default value of the parameter. Again, the type of this value will depend on the type of the kParameterDataType atom. This atom must be a correctly-formatted parameter atom that can be passed back to your component by client software without modification.

An example of a basic parameter description is shown in Listing 16 .

Listing 16 An example set of parameter description atoms



 
kParameterAtomTypeAndID, 101, noChildren,

{

    OSType { "sden" };      // atomType--the name of this parameter

    long { "1" };           // atomID--this is atom number 1

    kAtomNotInterpolated; // atomFlags--this parameter cannot be tweened

    string { "Scratch Density" }; // atomName--the name of the parameter

            // as it will appear in the standard parameters dialog box

};



kParameterDataType, 101, noChildren,

{

    kParameterTypeDataLong;     // dataType--this parameter contains a

                                // long value

};



kParameterDataRange, 101, noChildren,

{

    long { "0" };       // minimumValue

    long { "25" };      // maximumValue

    long { "1" };       // scaleFactor--no scaling is applied to this

                        // parameter

    long { "0" };       // precision--0 indicates that this parameter is

                        // not a floating-point value

};



kParameterDataBehavior, 101, noChildren,

{

    kParameterItemControl;  // behaviorType--this parameters should be

                            // represented by a slider

    long { "0" };           // behaviorFlags - no flags

};



kParameterDataDefaultItem, 101, noChildren,

{

    long { "5" };           // the default value of the parameter

};